home *** CD-ROM | disk | FTP | other *** search
/ Popular Request / By Popular Request (Arsenal Computer)(SysOptics Distribution System).ISO / amiga1 / adev1121.lha / readme < prev    next >
Text File  |  1994-03-03  |  15KB  |  296 lines
  1. /*
  2.  * Copyright 1992 Stan Burton
  3.  *
  4.  * Permission to use, copy, modify, distribute, and sell this software
  5.  * and its documentation for any purpose is hereby granted without fee,
  6.  * provided that the above copyright notice appear in all copies and
  7.  * that both that copyright notice and this permission notice appear in
  8.  * supporting documentation, and that the name of Stan Burton not be used
  9.  * in advertising or publicity pertaining to distribution of the software
  10.  * without specific, written prior permission.  I make no representations
  11.  * about the suitability of  this software for any purpose.  It is
  12.  * provided "as is" without express or implied warranty.
  13.  *
  14.  * THE ABOVE-NAMED DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  15.  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT
  16.  * SHALL STAN BURTON BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  17.  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  18.  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  19.  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  20.  * OF THIS SOFTWARE.
  21.  *
  22.  * Author:
  23.  *        Stan Burton
  24.  *
  25.  *        1978 26 St. SE
  26.  *        Medicine Hat, AB, CANADA
  27.  *              T1A 2G8
  28.  */
  29.  
  30. SOME OF THESE PROGRAMS REQUIRE AMIGADOS 2.0
  31.  
  32. slink requires V2.0, slink1.3 is a slower AmigaDOS V1.3 compatible
  33. replacement for slink.  All other programs are V1.3 and 2.0 compatible.
  34.  
  35.  
  36. INSTALLATION
  37.  
  38. Installation is simple. If you are reading this, and logically you must
  39. be, then step 1 is done.
  40.  2.  The directory containing this file and the other files unpacked from
  41.        the archive should be added to your path (see warning about slink
  42.        below).
  43.  3.  Assign ADev11: to this directory.  This is required mainly for the
  44.        C compiler.
  45.  4.  Read the docs! I know you won't until you run into trouble, but make
  46.        sure you have read them before you come to me for help.
  47.  
  48.  
  49. CONVERTING FROM MOTOROLA STANDARD FORMAT
  50.  
  51. This assembler differs from the Motorola format in a few ways that will
  52. be noticed when you try to assemble such a file.
  53.  
  54. 1. The '*' used to indicate current address is replaced with '.'.
  55. 2. The usage 'sym1 equ *' would translate to 'sym1 equ .' which has a
  56.      bug (see bug list); it should really be just 'sym1'.
  57. 3. String constants are enclosed in double quotes instead of single
  58.      quotes.
  59. 4. The bit operands had a space separating the mask and label (if one),
  60.      This assembler uses a comma to separate these.
  61. 5. The arguments of bit operations such as BRCLR and BRSET must be
  62.      separated by commas; not spaces as in the Motorola format.
  63. 6. Sasm requires a PROCESSOR pseudo-op at the start of the source file.
  64.      Without it there are no instruction mnemonics only pseudo-ops.
  65.  
  66. Other problems, unrelated to the format are;
  67.  
  68. 1. Most Motorola files did not use segments, they must be used here.
  69.  
  70.  
  71. COMMON PROBLEMS
  72.  
  73. slink reports 'Error 600: Invalid command MEM'
  74.         You own SAS/C 6.x and are seeing a name clash.  You will have
  75.           to refer to slink using a path, usually ADev11:slink
  76. slink reports 'unknown hunk type'
  77.     the assembler may have been aborted leaving a partial file
  78.     the assembler source file may have code outside of a segment
  79. sc11 reports a problem in byte_length
  80.     certain errors in the C source file may cause SC11 to emit
  81.       68000 instructions.  For example
  82.         char c, *chr_ptr;
  83.         c = *(char *)*chr_ptr;
  84.     this may be a legitimate bug.  If there is nothing wrong
  85.       with the C source, reduce the source file as much as
  86.       possible and send it to me.
  87.  
  88.  
  89. KNOWN BUGS ---------------------------------
  90. SC11 - see bug_list in C/
  91. SAsm - a DC.l with a symbol can cause assembler to hang
  92. ALL - the docs should have elaborative error message descriptions
  93. SDis - requires at least one non-executable byte after the last executable
  94.   opcode in memory or it will not print out the disassembled data
  95. Slib - the -r option does nothing.
  96.  
  97.  
  98. RELEASE CHANGES
  99.  
  100. 2.1 ----------------------------------------
  101. SC11 - The code generator optimization intended for brclr optimizations
  102.   could be used with the wrong address mode.
  103. SC11 - A particular combination of events in a switch statement would
  104.   omit the generation of a compare instruction
  105. SAsm - I have added high level if-else-endif statements.  See the docs.
  106. Docs - There is now an AmigaGuide version of the documents.
  107. Slink - has a new reserved keyword that makes it possible to generate a
  108.   checksum for your rom.  See the docs.
  109. Slink - would leave libraries open and memory unfreed if an error occurred
  110.   during the library scan.
  111. 2.0b ---------------------------------------
  112. SC11 - situations such as a large bodied if statement in a for loop could
  113.   cause a byte_length error message
  114. C_lib.lib - added getch a non-echoed version of getc
  115. C_lib.lib - fixed incorrect handling of default in switch stmt
  116. SC11 - could generate a short branch where a long branch is required
  117.   if there are DC.x statements in between.
  118. C_lib.lib - various problems with stdio functions fixed
  119. C_lib.lib - more functions added (strcpy, strcmp, strcat plus 'n' versions
  120. struct.inc - new file for defining C like structures in assembly
  121. stdio.h - added conditional definition of NULL
  122. SAsm - fixed incorrect generation for read-modify-write ops using direct,
  123.   or either indexed mode
  124. SAsm - enabled SAsm to recognize and ignore STABS and STABN debug info
  125. SC11 - fixed minor peep-hole optimizer bug, not recognizing 'tba'
  126. SC11 - enabled the generation of debugging information
  127. SAsm - improved handling of equated symbols when used in operations
  128.   so that un-needed promotions are not done.
  129. SAsm - improved handling of equated symbols to reduce promotions to
  130.   word addr from byte addr when not required.  For example
  131.     lab   equ   4
  132.           ldaa  lab     <== this was formerly promoted to word addr
  133. SAsm - corrected reversed opcodes for 6805 word addr mode and indexed word
  134.   addr
  135. SC11 - docs now contain a list of C functions but no function descriptions
  136.   especially required for the non ANSI funcitons
  137. 2.0a ---------------------------------------
  138. SC11 - added optimization to reduce if/while/conditional (*ptr & 0x80)
  139.   type expressions to brset/brclr instructions.
  140. SC11 - added optimization to remove tstb from all comparisons.  It is
  141.   not required since there are no 8 bit instructions that do not
  142.   correctly set the CCR flags
  143. SC11 - eliminated unneccesary promotion of unsigned types and allowed
  144.   literal constant integers to be classed as unsigned if they fit in
  145.   that range.
  146. Docs - the library reference referred to HC11.lib rather than lib11.lib
  147. SDis - will not disassemble small programs (fixed)
  148. SAsm - 16 bit logicals (andd, etc) had reversed accumulators
  149. HCload - fixed a problem with specifying a file without the -s option
  150. HCload - now has a -m option for boards like the mini-board that have
  151.   hardware echo built-in (this still doesn't work)
  152. SDis - now accepts a file containing code entry addresses
  153. MHex - now accepts command line values for EPROM start/end and interactive
  154.   operation is no longer required.
  155. Docs - filled rectangles were used to outline tables and they blocked out the
  156.   tables
  157. HCload - once again the version distributed was a version behind the docs
  158. MHex - some numbers were being printed out in decimal rather than hex
  159. SDis - a problem with printing out nonexistant label references
  160. SDis - now accepts code entry addresses on the command line (see docs)
  161. SDis - would not accept more than one additional address due to incorrect parsing
  162. 2.0 ----------------------------------------
  163. HCload - small changes
  164. SAsm - bit ops don't allow direct address mode
  165. SAsm - equ isn't correct for symbols not in first hunk
  166. SAsm - 'sym equ 354/12' doesn't work (in fact many operations didn't)
  167. MHex - the output file is generated with one missing byte if an EPROM end
  168.   address is specified rather than using the default
  169. Slink always returns with an error code
  170. SAsm - A -o option is added to redirect the output to some other file
  171. SAsm - passing ? as the only argument to SAsm now prints the help info.
  172. SAsm - A serious flaw resulted from an earlier change.  References to
  173.   the second or later sections of the same segment were wrong.
  174. SAsm - IF, IFCONST and IFNCONST were rarely correctly evaluated
  175. 1.2c ----------------------------------------
  176. SAsm - operand field in listing is truncated and when there is no
  177.   operand the comment is indented.
  178. 1.2b ----------------------------------------
  179. HCload - The old version somehow sneaked into the 1.2 release; this
  180.   release contains the correct version.
  181. 1.2a ----------------------------------------
  182. SAsm - sym1 equ sym2 where sym2 is relocatable still results in a
  183.   non-relocatable reference.
  184.   OK - this just bit ME in the butt.  In the example above, sym1 is
  185.   now a constant only if the expression (sym2) is constant.  An
  186.   expression is constant if it contains only numeric constants and
  187.   constant symbols.  This may not be correct in all cases.
  188.   This fix corrects a related bug; if sym2 is a zpage (.z) symbol sym1
  189.   was not.
  190. SAsm - new opcodes CMPD and FCC for better compatability with
  191.   Motorola source
  192. 1.2 ----------------------------------------
  193. HCload was reworked in many ways by its original author Ron Eirich.
  194. slink - added a new map mode to the map output.  This displays where, in
  195.   memory, all the hunks from all the modules were placed.
  196. SDis was in far worse shape than I knew.  Many bug fixes and improvements.
  197. sasm mishandled direct references to XREF'd symbols by instructions
  198.   having a prebyte
  199. slink reports of address out of range now include the hunk relative
  200.   address AND the module name AND the absolute address
  201. SAsm - use of an EQUated symbol as the indexed offset or direct address
  202.   of a BSET or BCLR could, in some cases, cause an unusable .o file
  203.   to be produced.
  204. lib11.lib new functions for printing in octal are __put_oct_str_sm,
  205.   __put_oct_str, __put_oct_sm,  __put_oct.
  206. lib11.lib all put_functions now use a symbol called __z_blank that is
  207.   a leading zero blanking (lzb) flag/counter.  Its value is the number of
  208.   leading digits that you want to consider using lzb on.  For example,
  209.   these values printed with _put_asc (a word (5 digit) routine)
  210.   __z_blank | value = 99 | value = 9 | value = 0
  211.   ----------|------------|-----------|----------
  212.        3    |    99      |    09     |    00
  213.        4    |    99      |    9      |    0
  214.        5    |    99      |    9      |
  215.   Normally with a 5 digit routine you would use __z_blank = 4;
  216. lib11.lib sm functions __put_asc_sm, __put_hex_sm, __put_asc_str_sm and
  217.   __put_hex_str_sm now accept the value in the B register.  There are
  218.   new functions __put_asc_usm, __put_asc_str_usm and.
  219. SAsm - fcb and fdb did not treat constants the same as DC.b, particulary
  220.   with respect to symbols and XREFs.
  221. SAsm - fixed a long standing bug in branches to labels in the second or
  222.   later sections of a segment within a module.  This could have produced
  223.   incorrect code in some cases in others it would appear as a branch out
  224.   of range error.  This also affected the use of the '.' symbol.
  225. lib11.lib all functions are now preceeded by __ (assembler level). Done
  226.   for compatibility with C environment.
  227. lib11.lib the functions put_asc, put_asc_sm, put_asc_u, put_hex and
  228.   put_hex_sm now modify the X register.  There are also new versions
  229.   put_asc_str, put_asc_str_sm, put_asc_str_u that put the result in the
  230.   string pointed to by the X register input.
  231. SAsm now accepts the .z force on XREF and SEG.  This causes all symbols
  232.   defined by such an XREF or declared in such a segment to use zero page
  233.   addressing where applicable.  At the same time the restriction on
  234.   automatic generation of page zero references with constant (not symbolic)
  235.   addresses is lifted.
  236. slink has been changed to apply special treatment to segments with the
  237.     name IDATA.  (see docs for more details)
  238. SAsm reported the wrong version number while running
  239. SAsm undefined symbols were reported obliquely, due to a change in R1.1 I
  240.     believe.
  241. SAsm would not allow a symbol to be XDEF'd after it was defined.
  242. SAsm an error resulting from a change just prior to the original release
  243.     made it impossible to successfully reuse a segment within the same
  244.     source file.
  245. SAsm (HC11) has been modified to accept three new pseudo-mnemonics.  They
  246.     are ANDD, EORD, ORD from the 68HC16 instruction set.  They produce, in
  247.     the case of ANDD, an ANDB followed by an ANDA.  Therefore the result
  248.     is correct but only the N bit of the CCR flags is correct.  The
  249.     mnemonics are valid with all HC11 addressing modes.  This change was
  250.     made to prepare for the C compiler and was done in the assembler
  251.     because it could not be done with macros.
  252. 1.1 ----------------------------------------
  253. SDis became confused if the S-record file to be dis-assembled contained a
  254.     value for address FFFF. This would usually result in a crash.
  255. SDis default for (y/N) question would default to Y instead
  256. SAsm failed to recognize that a negative number or expression result >= -128
  257.     could fit into an 8 bit immediate operand resulting in an illegal
  258.     addressing mode error for instructions such as this.
  259.     ldab    #1-2
  260. SAsm - Minor improvement in pass handling under special conditions
  261. SAsm - Unary operations and binary operations involving a single XREF'd symbol
  262.     and an operator other than addition are not legal, but were not detected
  263.     by the assembler and produced incorrect code.
  264. It was not noted anywhere in the documents that some of the programs require
  265.     AmigaDOS 2.0.  Now only slink does and there is a slink1.3 replacement
  266. slink was accessing memory on an odd boundary which would cause a crash on
  267.     68000 68010 processors
  268. The 68HC11 registers include file 68HC11.inc is now included in the release.
  269.     It is not quite complete yet ... as time permits.
  270. A new utility, MHex, has been added which allows conversion of S record
  271.     files to straight binary.  The source is also included in case you have
  272.     a particular format requirement.  I would appreciate receiving any such
  273.     conversions and I will try to make one grand unified utility out of them.
  274. A simple monitor program is provided, along with source, I like it because
  275.     its extensible command set allows me to easily develop command driven
  276.     programs.
  277. New library functions for printing values as hex ascii are available.
  278. HCload was modified to work with any serial-type device and any unit number.
  279. Two of the listed library functions were somehow left out of the library.
  280.  
  281. 1.0 ----------------------------------------
  282. SAsm, slink and slib now handle 68HC16 mnemonics and addressing modes as
  283. far as I have been able to test.  I do not have a 68HC16 processor and
  284. have relied on Motorola printed documents.
  285.  
  286. The doc file doc.txt is generated from the .ps file for those who don't
  287. have access to a postscript printer or converter.
  288.  
  289. I can be reached at:
  290. internet sburton@dres.dnd.ca      <= NOTE: change
  291. BIX      sburton
  292. mail     Stan Burton
  293.          1978 26 St. SE
  294.          Medicine Hat, AB CANADA
  295.          T1A 2G8
  296.